/**
 * @file sidebarwidget.h
 * @brief 侧边栏组件头文件 - 应用程序主要导航界面
 *
 * SidebarWidget是应用程序的主要导航组件，提供：
 * - 用户信息展示和头像显示
 * - 主要功能模块的导航按钮
 * - 侧边栏展开/收缩功能
 * - 主题切换和样式管理
 * - 用户登出和设置入口
 */

#ifndef SIDEBARWIDGET_H
#define SIDEBARWIDGET_H

#include <QWidget>                      // Qt基础窗口组件
#include <QVBoxLayout>                  // 垂直布局管理器
#include <QHBoxLayout>                  // 水平布局管理器
#include <QLabel>                       // 文本和图像标签组件
#include <QPushButton>                  // 按钮组件
#include <QFrame>                       // 框架和分隔线组件
#include <QScrollArea>                  // 滚动区域组件
#include <QListWidget>                  // 列表组件
#include <QGroupBox>                    // 分组框组件
#include <QPropertyAnimation>           // 属性动画组件
#include <QGraphicsDropShadowEffect>    // 阴影效果组件
#include "authservice.h"

/**
 * @class SidebarWidget
 * @brief 侧边栏导航组件
 *
 * 提供应用程序的主要导航界面，支持展开/收缩模式，
 * 包含用户信息、导航菜单、快捷操作等功能区域。
 */
class SidebarWidget : public QWidget
{
    Q_OBJECT  // 启用Qt元对象系统

public:
    explicit SidebarWidget(AuthService *authService, QWidget *parent = nullptr);
    virtual ~SidebarWidget();

    void updateUserInfo(const AuthService::UserInfo &userInfo);
    void setCollapsed(bool collapsed);
    bool isCollapsed() const { return m_collapsed; }
    void setTheme(const QString &theme);

    /**
     * @brief 设置退出按钮模式
     * @param isInGame 是否在游戏中
     *
     * 当isInGame为true时，按钮显示"退出游戏"
     * 当isInGame为false时，按钮显示"安全退出"
     */
    void setExitButtonMode(bool isInGame);

signals:
    void gameServersClicked();
    void friendsClicked();
    void settingsClicked();
    void profileClicked();
    void statisticsClicked();
    void helpClicked();
    void logoutClicked();
    void exitGameClicked();  ///< 退出游戏信号

private slots:
    void onToggleCollapse();
    void onMenuItemClicked();

private:
    // === UI初始化和设置方法 ===
    void setupUI();                        ///< 初始化整体UI布局和组件
    void setupUserProfile();               ///< 设置用户资料显示区域
    void setupNavigationMenu();            ///< 设置导航菜单按钮
    void setupQuickActions();              ///< 设置快捷操作按钮
    void setupFooter();                    ///< 设置底部区域（登出、收缩按钮）
    void applyStyles();                    ///< 应用样式表和主题
    void updateCollapseState();            ///< 更新展开/收缩状态
    void updateAvatarSize(int size);       ///< 动态更新头像大小
    void forceUpdateUserInfo();            ///< 强制更新用户信息显示
    void initializeButtonProperties();     ///< 初始化按钮属性和状态

    // === UI组件创建辅助方法 ===
    QPushButton* createMenuButton(const QString &text, const QString &icon, const QString &tooltip = QString());  ///< 创建统一样式的菜单按钮
    void addSeparator();                   ///< 添加分隔线
    void addMenuSeparator(QVBoxLayout *layout);  ///< 在指定布局中添加菜单分隔线

    // === 服务依赖 ===
    /**
     * @brief 用户认证服务指针
     *
     * 用于获取当前用户信息、监听认证状态变化、处理登出操作。
     * 通过构造函数注入，确保侧边栏能够实时反映用户状态。
     */
    AuthService *m_authService;

    // === 主布局组件 ===
    /**
     * @brief 侧边栏主布局管理器
     *
     * 垂直布局，管理整个侧边栏的顶层结构。
     * 包含滚动区域，确保内容在不同窗口高度下都能正常显示。
     */
    QVBoxLayout *m_mainLayout;

    /**
     * @brief 滚动区域容器
     *
     * 当侧边栏内容超过可视区域高度时，提供滚动功能。
     * 确保所有导航项目都能被用户访问，特别是在小屏幕设备上。
     */
    QScrollArea *m_scrollArea;

    /**
     * @brief 滚动区域内的内容容器
     *
     * 作为滚动区域的子组件，承载所有实际的UI内容。
     * 通过设置为滚动区域的widget来实现滚动功能。
     */
    QWidget *m_contentWidget;

    /**
     * @brief 内容容器的布局管理器
     *
     * 垂直布局，管理用户资料、导航菜单、底部区域等主要组件的排列。
     * 设置适当的间距和边距，确保界面美观和易用性。
     */
    QVBoxLayout *m_contentLayout;

    // === 用户资料显示区域 ===
    /**
     * @brief 用户资料区域容器
     *
     * 包含用户头像和基本信息的顶部区域。
     * 在展开状态显示完整信息，收缩状态只显示头像。
     */
    QWidget *m_userProfileWidget;

    /**
     * @brief 用户资料区域的水平布局
     *
     * 管理头像和用户信息的水平排列。
     * 左侧放置头像容器，右侧放置用户信息文本。
     */
    QHBoxLayout *m_userProfileLayout;

    /**
     * @brief 头像容器组件
     *
     * 包装头像标签，提供固定的尺寸和样式。
     * 支持圆形头像显示和悬停效果，可点击查看用户资料。
     */
    QWidget *m_avatarContainer;

    /**
     * @brief 用户头像标签
     *
     * 显示用户头像图片或默认头像。
     * 支持不同尺寸的头像显示（展开/收缩状态）。
     * 图片格式：通常为圆形裁剪的用户头像。
     */
    QLabel *m_avatarLabel;

    /**
     * @brief 用户信息文本容器
     *
     * 包含用户名、状态、等级等文本信息的容器。
     * 在收缩状态下隐藏，展开状态下显示在头像右侧。
     */
    QWidget *m_userInfoWidget;

    /**
     * @brief 用户信息的垂直布局
     *
     * 管理用户名、状态、等级标签的垂直排列。
     * 确保文本信息层次清晰，易于阅读。
     */
    QVBoxLayout *m_userInfoLayout;

    /**
     * @brief 用户名显示标签
     *
     * 显示当前登录用户的用户名。
     * 字体较大，作为用户信息的主要标识。
     * 文本内容来自AuthService::UserInfo::username。
     */
    QLabel *m_usernameLabel;

    /**
     * @brief 用户状态显示标签
     *
     * 显示用户当前状态（在线、离线、忙碌等）。
     * 使用不同颜色表示不同状态，提供视觉反馈。
     * 可能的状态：在线(绿色)、离线(灰色)、忙碌(橙色)。
     */
    QLabel *m_statusLabel;

    /**
     * @brief 用户等级显示标签
     *
     * 显示用户等级或积分信息。
     * 可能显示内容：等级数字、经验值、称号等。
     * 为游戏化体验提供用户成就感。
     */
    QLabel *m_levelLabel;

    // === 导航菜单区域 ===
    /**
     * @brief 导航菜单分组容器
     *
     * 包含所有主要功能模块的导航按钮。
     * 是侧边栏的核心功能区域，提供应用程序的主要入口。
     */
    QWidget *m_navigationGroup;

    /**
     * @brief 导航菜单的垂直布局
     *
     * 管理所有导航按钮的垂直排列。
     * 设置统一的按钮间距和对齐方式，确保界面整洁。
     */
    QVBoxLayout *m_navigationLayout;

    /**
     * @brief 游戏服务器按钮
     *
     * 导航到游戏服务器列表和管理界面。
     * 图标：🎮 或 server图标
     * 功能：浏览服务器、筛选、加入游戏等核心功能。
     * 这是应用程序的主要功能入口。
     */
    QPushButton *m_gameServersButton;



    /**
     * @brief 好友系统按钮
     *
     * 导航到好友列表和社交功能界面。
     * 图标：👥 或 friends图标
     * 功能：好友管理、在线状态、邀请游戏、聊天等社交功能。
     */
    QPushButton *m_friendsButton;

    /**
     * @brief 统计数据按钮
     *
     * 导航到用户游戏统计和数据分析界面。
     * 图标：📊 或 chart图标
     * 功能：游戏记录、胜率统计、排名变化、成绩分析等。
     */
    QPushButton *m_statisticsButton;

    // === 个人功能按钮区域 ===
    /**
     * @brief 个人资料按钮
     *
     * 导航到用户个人资料编辑界面。
     * 图标：👤 或 profile图标
     * 功能：编辑个人信息、头像上传、隐私设置等。
     */
    QPushButton *m_profileButton;

    /**
     * @brief 应用设置按钮
     *
     * 导航到应用程序设置和配置界面。
     * 图标：⚙️ 或 settings图标
     * 功能：主题切换、语言设置、通知配置、快捷键设置等。
     */
    QPushButton *m_settingsButton;

    /**
     * @brief 帮助和支持按钮
     *
     * 导航到帮助文档和用户支持界面。
     * 图标：❓ 或 help图标
     * 功能：使用教程、常见问题、联系客服、反馈建议等。
     */
    QPushButton *m_helpButton;

    // === 底部功能区域 ===
    /**
     * @brief 底部功能区域容器
     *
     * 包含登出按钮和侧边栏收缩/展开控制按钮。
     * 位于侧边栏底部，提供重要的系统级操作。
     */
    QWidget *m_footerWidget;

    /**
     * @brief 底部区域的垂直布局
     *
     * 管理底部按钮的排列和间距。
     * 确保按钮在不同状态下都能正确显示。
     */
    QVBoxLayout *m_footerLayout;

    /**
     * @brief 用户登出按钮
     *
     * 执行用户登出操作的按钮。
     * 图标：🚪 或 logout图标
     * 功能：清除用户会话、返回登录界面、清理本地数据。
     * 点击后会弹出确认对话框，防止误操作。
     */
    QPushButton *m_logoutButton;

    /**
     * @brief 侧边栏收缩/展开控制按钮
     *
     * 控制侧边栏展开和收缩状态的切换按钮。
     * 图标：◀️ (展开状态) 或 ▶️ (收缩状态)
     * 功能：在展开模式和收缩模式之间切换，节省屏幕空间。
     */
    QPushButton *m_collapseButton;

    // === 状态管理属性 ===
    /**
     * @brief 侧边栏收缩状态标志
     *
     * 记录当前侧边栏是否处于收缩状态。
     * true：收缩状态（只显示图标，宽度为m_collapsedWidth）
     * false：展开状态（显示图标和文字，宽度为m_expandedWidth）
     * 用于控制UI元素的显示/隐藏和布局调整。
     */
    bool m_collapsed;

    /**
     * @brief 侧边栏展开状态的宽度
     *
     * 侧边栏完全展开时的像素宽度。
     * 默认值：220像素（来自Config::getSidebarExpandedWidth()）
     * 需要足够宽度显示：头像(60px) + 文字区域(140px) + 边距(20px)
     */
    int m_expandedWidth;

    /**
     * @brief 侧边栏收缩状态的宽度
     *
     * 侧边栏收缩时的最小像素宽度。
     * 默认值：60像素（来自Config::getSidebarCollapsedWidth()）
     * 计算：图标尺寸(32px) + 边距和点击区域(28px)
     */
    int m_collapsedWidth;

    /**
     * @brief 当前应用主题标识
     *
     * 记录当前使用的主题名称。
     * 可能的值："dark"（深色主题）、"light"（浅色主题）
     * 用于主题切换时保持状态一致性，影响颜色和样式的应用。
     */
    QString m_currentTheme;

    /**
     * @brief 是否在游戏中的状态标识
     *
     * 用于控制退出按钮的显示模式：
     * - true：显示"退出游戏"，点击返回游戏服务器选择界面
     * - false：显示"安全退出"，点击退出应用程序
     */
    bool m_isInGame;

    // === 动画控制 ===
    /**
     * @brief 收缩/展开动画控制器
     *
     * 控制侧边栏在展开和收缩状态之间切换的平滑动画。
     * 动画属性：侧边栏的宽度(width)
     * 动画时长：通常200-300毫秒
     * 缓动曲线：QEasingCurve::InOutQuad（自然的加速减速效果）
     *
     * 动画过程：
     * - 展开：从m_collapsedWidth平滑过渡到m_expandedWidth
     * - 收缩：从m_expandedWidth平滑过渡到m_collapsedWidth
     * - 同时控制文字元素的淡入淡出效果
     */
    QPropertyAnimation *m_collapseAnimation;

    // 样式
    QString m_primaryColor;
    QString m_secondaryColor;
    QString m_backgroundColor;
    QString m_textColor;
    QString m_hoverColor;
    QString m_activeColor;
};

#endif // SIDEBARWIDGET_H
